Node / public / precursor-lxmfchat.git / files / xous-core / docs / arguments.md

Displaying Rendered • View raw • Download

This section has been superceded by the Xous Book chapter on Arguments

The contents here are historical, and not normative.

Xous arguments are automatically generated by tools/src/bin/create-image.rs. Most

parameters are extracted from the soc.svd file provided to the builder script.

Xous arguments are passed by giving a page-aligned address pointed to

by register T383838$a0. This uses IFF-style tags with the following format:

T282828

The size is in little endian byte order, and does not include the 8

bytes describing the tag type or the size. The data must be padded to

4-bytes, so the T383838size field is in 4-byte words. That is, a tag with

four bytes of contents would have a T383838size of T3838381.

The T383838XArg block must be first.

| Tag | Description

| ---- | ------------

| XArg | Xous Args. This indicates the size of the entire block (including the XArg tag and size), as well as the user RAM area, and can be used to determine how many pages to save for this block. This must be the first argument.

| BFlg | Bootloader config flags.

| MREx | Extra memory ranges. This is a series of offset/size pairs indicating additional memory regions in the system beyond RAM, as well as a code name for the memory page. It does not include system RAM.

| XKrn | Kernel source specification. Includes the offset of the kernel in RAM as well as its size. Does not need to be page-aligned, unless NO_COPY is 1.

| IniE | Initial program specification, based on a degenerate ELF header. This includes the load offset of the binary, as well as the size of each section. Does not need to be page-aligned unless NO_COPY is 1. May appear more than once, for each of the initial processes.

| IniF | Same as IniE, except laid out on disk such that the sub-page address offsets correspond 1:1 with the virtual memory representation, allowing an execute in place (XIP) mapping of code into the virtual memory space.

The overall size of the argument block. This must come first. This tag

has four words of contents, which is the number of words of data plus

the system memory definition. Therefore, a minimum boot tag structure

would have an T383838XArg size of 5: One word for the tag, one for the

crc+size, and four for the contents of the T383838XArg region.

| Offset | Size | Name | Description

| ------- | ---- | --------- | -----------

| 0 | 4 | Arg Size | The size of the entire args structure, including all headers, but excluding any trailing data (such as executables)

| 4 | 4 | Version | Version of the XArg structure. Currently T3838381.

| 8 | 4 | RAM Start | The origin of system RAM, in bytes

| 12 | 4 | RAM Size | The size of system RAM, in bytes

| 16 | 4 | RAM Name | A printable name for system RAM

This configures various bootloader flags. It consists of a single word

of data.

• 0x00000001 T383838NO_COPY -- Skip copying data to RAM.

• 0x00000002 T383838ABSOLUTE -- All program addresses are absolute.

Otherwise, they're relative to the start of the config block.

• 0x00000004 T383838DEBUG -- Allow the kernel to access memory inside user

programs, which allows a debugger to run in the kernel.

Extra memory regions. See memory.md for more information.

The T383838IniE argument describes how to load initial processes. The fields T383838size, T383838flags, and T383838offset occupy 64 bits (8 bytes). The

T383838OFFSET is a full 32-bit address. The T383838SIZE field is in units of

bytes, however as it is only 24 bits, meaning the largest section size

is T3838382^24 bytes. Thus when printed as T383838u32, an IniE/F argument has this structure:

T282828

Where T383838J is the offset, T383838K is the flag, and T383838L is the size. There are about

7 pairs of these, one corresponding to each section of the MiniElf:

• LOAD_OFFSET -- Position in RAM relative to the start of the arguments

block where this program is stored, or an absolute value if T383838ABSOLUTE

is T3838381.

• ENTRYPOINT - Virtual memory address of the T383838_start() function

• SECTION1_OFFSET -- Virtual memory address of the first memory section

• SECTION1_SIZE -- Size of the first memory section

• SECTION1_FLAGS -- Flags describing the first memory section

• SECTION2_OFFSET -- Virtual memory address of the second memory section

• SECTION2_SIZE -- Size of the second memory section

• SECTION2_FLAGS -- Flags describing the second memory section

• ...

• SECTIONn_OFFSET -- Virtual memory address of the T383838nth memory section

• SECTIONn_SIZE -- Size of the T383838nth memory section

• SECTIONn_FLAGS -- Flags describing the T383838nth memory section

The T383838FLAGS field contains the following four bits. Any region may be

marked NOCOPY, however RISC-V does not allow regions to be marked

"Write-only":

| Bit | Binary | Name | Description

| ------ | ----------- | ---------- | ---------------------------------------------

| 0 | 0b000001 | NOCOPY | No data should be copied -- useful for T383838.bss

| 1 | 0b000010 | WRITABLE | Region will be allocated with the "W" bit

| 2 | 0b000100 | READABLE | Region will be allocated with the "R" bit

| 3 | 0b001000 | EXECUTABLE | Region will be allocated with the "X" bit

| 4 | 0b010000 | EHFLAG | Region is an EHFLAG region

| 5 | 0b100000 | EHFLAGHDR | Region is an EHFLAGHEADER region

Programs cannot access the final four megabytes, as this memory

is reserved for the kernel.

This describes the kernel image. This image will get mapped into every

process within the final 4 megabytes, and therefore the text and data

offsets must be in the range T3838380xffc0_0000 - T3838380xfff0_0000.

• LOAD_OFFSET -- Physical address (or offset) where the kernel is stored

• TEXT_OFFSET -- Virtual memory address where the kernel expects the

program image to live. This should be T3838380xffd00000

• TEXT_SIZE -- Size of the text section. This indicates how many bytes

to copy from the boot image.

• DATA_OFFSET -- Virtual memory address where the kernel expects the

.data/.bss section to be. This should be above T3838380xffd00000 and below

T3838380xffe00000

• DATA_SIZE -- Size of the .data section

• BSS_SIZE -- The size of the .bss section, which immediately follows .data

• ENTRYPOINT -- Virtual address of the T383838_start() function

The kernel will run in Supervisor mode, and have its own private stack.

T383838PNam maps process IDs to process names. If multiple T383838PNam tags exist

within a block, the first one that is encountered should take precedence.

This tag is a series of entries that take the following format:

| Size (bytes) | Name | Description

| --------- | ---- | -----

| 4 | PID | ID of the process that this name describes

| 4 | Length | The length of the data that follows

| varies | Data | The UTF-8 name string